home *** CD-ROM | disk | FTP | other *** search
/ Mac-Source 1994 July / Mac-Source_July_1994.iso / Other Langs / Tickle-4.0 (tcl) / library / help / tcl / strings / regexp < prev    next >
Encoding:
Text File  |  1993-10-26  |  6.4 KB  |  135 lines  |  [TEXT/$Tcl]
  1.  
  2.           regexp ?switches? exp string  ?matchVar?  ?subMatchVar  sub-
  3.           MatchVar ...?
  4.  
  5.  
  6.      DESCRIPTION
  7.           Determines whether the regular expression exp  matches  part
  8.           or all of string and returns 1 if it does, 0 if it doesn't.
  9.  
  10.           If additional arguments are specified after string then they
  11.           are  treated  as  the  names of variables in which to return
  12.           information about  which  part(s)  of  string  matched  exp.
  13.           MatchVar will be set to the range of string that matched all
  14.           of exp.  The first subMatchVar will contain  the  characters
  15.           in string that matched the leftmost parenthesized subexpres-
  16.           sion within exp, the next subMatchVar will contain the char-
  17.           acters  that matched the next parenthesized subexpression to
  18.           the right in exp, and so on.
  19.  
  20.           If the initial arguments to regexp start with  -  then  they
  21.           are   treated  as  switches.   The  following  switches  are
  22.           currently supported:
  23.  
  24.           -nocase   Causes  upper-case  characters  in  string  to  be
  25.                     treated as lower case during the matching process.
  26.  
  27.           -indices  Changes  what  is  stored  in  the   subMatchVars.
  28.                     Instead  of  storing  the matching characters from
  29.                     string, each variable will contain a list  of  two
  30.                     decimal  strings  giving  the indices in string of
  31.                     the first and  last  characters  in  the  matching
  32.                     range of characters.
  33.  
  34.           --        Marks the end of switches.  The argument following
  35.                     this  one will be treated as exp even if it starts
  36.                     with a -.
  37.  
  38.           If there are more subMatchVar's  than  parenthesized  subex-
  39.           pressions  within  exp,  or if a particular subexpression in
  40.           exp doesn't match the string (e.g. because it was in a  por-
  41.           tion  of  the  expression  that  wasn't  matched),  then the
  42.           corresponding subMatchVar  will  be  set  to  ``-1  -1''  if
  43.           -indices has been specified or to an empty string otherwise.
  44.  
  45.  
  46.      REGULAR EXPRESSIONS
  47.           Regular expressions are implemented  using  Henry  Spencer's
  48.           package  (thanks,  Henry!),  and  much of the description of
  49.           regular expressions below is copied verbatim from his manual
  50.           entry.
  51.  
  52.           A regular expression is zero or more branches, separated  by
  53.           ``|''.    It  matches  anything  that  matches  one  of  the
  54.           branches.
  55.  
  56.           A branch is zero or more pieces, concatenated.  It matches a
  57.           match  for  the  first,  followed by a match for the second,
  58.           etc.
  59.  
  60.           A piece is an atom possibly followed  by  ``*'',  ``+'',  or
  61.           ``?''.  An atom followed by ``*'' matches a sequence of 0 or
  62.           more matches of the atom.  An atom followed by ``+'' matches
  63.           a  sequence  of 1 or more matches of the atom.  An atom fol-
  64.           lowed by ``?'' matches a match of  the  atom,  or  the  null
  65.           string.
  66.  
  67.           An atom is a regular expression in parentheses  (matching  a
  68.           match  for  the  regular  expression),  a range (see below),
  69.           ``.'' (matching any single character), ``^''  (matching  the
  70.           null  string  at  the  beginning of the input string), ``$''
  71.           (matching the null string at the end of the input string), a
  72.           ``\''  followed by a single character (matching that charac-
  73.           ter), or a  single  character  with  no  other  significance
  74.           (matching that character).
  75.  
  76.           A range is a sequence of characters enclosed in ``[]''.   It
  77.           normally matches any single character from the sequence.  If
  78.           the sequence begins with ``^'', it matches any single  char-
  79.           acter  not from the rest of the sequence.  If two characters
  80.           in the sequence are separated by ``-'',  this  is  shorthand
  81.           for  the  full  list  of ASCII characters between them (e.g.
  82.           ``[0-9]'' matches any decimal digit).  To include a  literal
  83.           ``]''  in the sequence, make it the first character (follow-
  84.           ing a possible ``^'').  To include a literal ``-'', make  it
  85.           the first or last character.
  86.  
  87.  
  88.      CHOOSING AMONG ALTERNATIVE MATCHES
  89.           In general there may be more than one way to match a regular
  90.           expression  to  an  input string.  For example, consider the
  91.           command
  92.  
  93.                regexp  (a*)b*  aabaaabb  x  y
  94.  
  95.           Considering only the rules given so far, x and y  could  end
  96.           up  with  the values aabb and aa, aaab and aaa, ab and a, or
  97.           any of several other combinations.  To resolve  this  poten-
  98.           tial  ambiguity  regexp chooses among alternatives using the
  99.           rule ``first then longest''.  In other  words,  it  consders
  100.           the  possible  matches  in  order working from left to right
  101.           across the input string and the pattern, and it attempts  to
  102.           match longer pieces of the input string before shorter ones.
  103.           More specifically, the following rules apply  in  decreasing
  104.           order of priority:
  105.  
  106.           [1]  If a regular expression could match two different parts
  107.                of  an  input  string  then  it will match the one that
  108.                begins earliest.
  109.  
  110.           [2]  If a regular expression contains | operators  then  the
  111.                leftmost matching sub-expression is chosen.
  112.  
  113.           [3]  In *, +, and ? constructs, longer matches are chosen in
  114.                preference to shorter ones.
  115.  
  116.           [4]  In sequences of expression  components  the  components
  117.                are considered from left to right.
  118.  
  119.           In the example from above, (a*)b*  matches  aab:   the  (a*)
  120.           portion  of the pattern is matched first and it consumes the
  121.           leading aa; then the b* portion of the pattern consumes  the
  122.           next b.  Or, consider the following example:
  123.  
  124.                regexp  (ab|a)(b*)c  abc  x  y  z
  125.           After this command x will be abc, y will be ab, and  z  will
  126.           be an empty string.  Rule 4 specifies that (ab|a) gets first
  127.           shot at the input string and Rule 2 specifies  that  the  ab
  128.           sub-expression is checked before the a sub-expression.  Thus
  129.           the b has already been claimed before the (b*) component  is
  130.           checked and (b*) must match an empty string.
  131.  
  132.  
  133.      KEYWORDS
  134.           match, regular expression, string
  135.